<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><title>Draft: eXtensible REST Services Protocol 0.1 -- Working Draft</title>
<meta http-equiv="Expires" content="Thu, 21 Jan 2010 22:57:24 +0000">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="eXtensible REST Services Protocol 0.1 -- Working Draft">
<meta name="generator" content="xml2rfc v1.33 (http://xml.resource.org/)">

  <script xmlns="http://www.w3.org/1999/xhtml" type="text/javascript">var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));</script>
      <script xmlns="http://www.w3.org/1999/xhtml" type="text/javascript">var pageTracker = _gat._getTracker("UA-12513552-1");pageTracker._trackPageview();</script>


<style type='text/css'><!--
        body {
                font-family: verdana, charcoal, helvetica, arial, sans-serif;
                font-size: small; color: #000; background-color: #FFF;
                margin: 2em;
        }
        h1, h2, h3, h4, h5, h6 {
                font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
                font-weight: bold; font-style: normal;
        }
        h1 { color: #900; background-color: transparent; text-align: right; }
        h3 { color: #333; background-color: transparent; }

        td.RFCbug {
                font-size: x-small; text-decoration: none;
                width: 30px; height: 30px; padding-top: 2px;
                text-align: justify; vertical-align: middle;
                background-color: #000;
        }
        td.RFCbug span.RFC {
                font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
                font-weight: bold; color: #666;
        }
        td.RFCbug span.hotText {
                font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
                font-weight: normal; text-align: center; color: #FFF;
        }

        table.TOCbug { width: 30px; height: 15px; }
        td.TOCbug {
                text-align: center; width: 30px; height: 15px;
                color: #FFF; background-color: #900;
        }
        td.TOCbug a {
                font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
                font-weight: bold; font-size: x-small; text-decoration: none;
                color: #FFF; background-color: transparent;
        }

        td.header {
                font-family: arial, helvetica, sans-serif; font-size: x-small;
                vertical-align: top; width: 33%;
                color: #FFF; background-color: #666;
        }
        td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
        td.author-text { font-size: x-small; }

        /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
        a.info {
                /* This is the key. */
                position: relative;
                z-index: 24;
                text-decoration: none;
        }
        a.info:hover {
                z-index: 25;
                color: #FFF; background-color: #900;
        }
        a.info span { display: none; }
        a.info:hover span.info {
                /* The span will display just on :hover state. */
                display: block;
                position: absolute;
                font-size: smaller;
                top: 2em; left: -5em; width: 15em;
                padding: 2px; border: 1px solid #333;
                color: #900; background-color: #EEE;
                text-align: left;
        }

        a { font-weight: bold; }
        a:link    { color: #900; background-color: transparent; }
        a:visited { color: #633; background-color: transparent; }
        a:active  { color: #633; background-color: transparent; }

        p { margin-left: 2em; margin-right: 2em; }
        p.copyright { font-size: x-small; }
        p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
        table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
        td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }

        ol.text { margin-left: 2em; margin-right: 2em; }
        ul.text { margin-left: 2em; margin-right: 2em; }
        li      { margin-left: 3em; }

        /* RFC-2629 <spanx>s and <artwork>s. */
        em     { font-style: italic; }
        strong { font-weight: bold; }
        dfn    { font-weight: bold; font-style: normal; }
        cite   { font-weight: normal; font-style: normal; }
        tt     { color: #036; }
        tt, pre, pre dfn, pre em, pre cite, pre span {
                font-family: "Courier New", Courier, monospace; font-size: small;
        }
        pre {
                text-align: left; padding: 4px;
                color: #000; background-color: #CCC;
        }
        pre dfn  { color: #900; }
        pre em   { color: #66F; background-color: #FFC; font-weight: normal; }
        pre .key { color: #33C; font-weight: bold; }
        pre .id  { color: #900; }
        pre .str { color: #000; background-color: #CFF; }
        pre .val { color: #066; }
        pre .rep { color: #909; }
        pre .oth { color: #000; background-color: #FCF; }
        pre .err { background-color: #FCC; }

        /* RFC-2629 <texttable>s. */
        table.all, table.full, table.headers, table.none {
                font-size: small; text-align: center; border-width: 2px;
                vertical-align: top; border-collapse: collapse;
        }
        table.all, table.full { border-style: solid; border-color: black; }
        table.headers, table.none { border-style: none; }
        th {
                font-weight: bold; border-color: black;
                border-width: 2px 2px 3px 2px;
        }
        table.all th, table.full th { border-style: solid; }
        table.headers th { border-style: none none solid none; }
        table.none th { border-style: none; }
        table.all td {
                border-style: solid; border-color: #333;
                border-width: 1px 2px;
        }
        table.full td, table.headers td, table.none td { border-style: none; }

        hr { height: 1px; }
        hr.insert {
                width: 80%; border-style: none; border-width: 0;
                color: #CCC; background-color: #CCC;
        }
--></style>
</head>
<body>
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
<tr><td class="header">Draft</td><td class="header">W. Candillon</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">G. Vanwormhoudt</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">Telecom Lille 1</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">January 11, 2010</td></tr>
</table></td></tr></table>
<h1><br />eXtensible REST Services Protocol 0.1 -- Working Draft</h1>

<h3>Abstract</h3>

<p>eXtensible REST Services Protocol is an application-level protocol to extend and compose Restful Web Services. This protocol is based on the plug-in architecture style to program and run composite Web Services.
</p>
<p>eXtensible REST Services Protocol aims to unify the experience and implementation of programmable web services into a single, open, community-driven protocol. Our goal is to run the Web as an extensible and distributed platform that enables rapid development of integrated Restful applications based on a plug-in model.
</p><a name="toc"></a><br /><hr />
<h3>Table of Contents</h3>
<p class="toc">
<a href="#license">1.</a>&nbsp;
License<br />
<a href="#notation-and-conventions">2.</a>&nbsp;
Notation and Conventions<br />
<a href="#xml-related-conventions">3.</a>&nbsp;
XML-Related Conventions<br />
<a href="#definitions">4.</a>&nbsp;
Definitions<br />
<a href="#model">5.</a>&nbsp;
Protocol Model<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#relationships">5.1.</a>&nbsp;
Relationships between Clients, Hosts and Plug-ins<br />
<a href="#discovery">6.</a>&nbsp;
Discovery<br />
<a href="#extensions">7.</a>&nbsp;
Extensions<br />
<a href="#extension-points">8.</a>&nbsp;
Extension Points<br />
<a href="#extension-registry">9.</a>&nbsp;
Extension Registry<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#host-plugin-interactions">9.1.</a>&nbsp;
Host/Plug-in interactions<br />
<a href="#runtime">10.</a>&nbsp;
Runtime<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#asynchronous-callback">10.1.</a>&nbsp;
Asynchronous Callback<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#synchronous-callback">10.2.</a>&nbsp;
Synchronous Callback<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#callback-parameters">10.3.</a>&nbsp;
Callback Parameters<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#decoration">10.4.</a>&nbsp;
Decoration<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#scheduling">10.5.</a>&nbsp;
Scheduling<br />
<a href="#security-considerations">11.</a>&nbsp;
Security Considerations<br />
<a href="#rfc.references1">12.</a>&nbsp;
References<br />
<a href="#extension-schema">Appendix&nbsp;A.</a>&nbsp;
Extension XML Schema<br />
<a href="#specification-feedback">Appendix&nbsp;B.</a>&nbsp;
Specification Feedback<br />
</p>
<br clear="all" />

<a name="license"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.1"></a><h3>1.&nbsp;
License</h3>

<p>
                This document is available under the <a href='http://creativecommons.org/licenses/by-sa/3.0/us/'>Creative Commons Attribution-Share Alike 3.0 license</a>. You are free to copy, distribute, transmit and adapt the work under the following conditions:
                </p>
<ul class="text">
<li>You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).
</li>
<li>If you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license.
</li>
</ul><p>
                Any of the above conditions can be <a href='http://creativecommons.org/licenses/by-sa/3.0/us/#'>waived</a> if you get permission from the copyright holder. In no way are any of the following rights affected by the license:
                </p>
<ul class="text">
<li>
                        Your fair dealing or <a href='http://wiki.creativecommons.org/Frequently_Asked_Questions#Do_Creative_Commons_licenses_affect_fair_use.2C_fair_dealing_or_other_exceptions_to_copyright.3F'>fair use</a> rights;
                        
<ul class="text">
<li>
                                Apart from the remix rights granted under this license, the author's <a href='http://wiki.creativecommons.org/Frequently_Asked_Questions#I_don.E2.80.99t_like_the_way_a_person_has_used_my_work_in_a_derivative_work_or_included_it_in_a_collective_work.3B_what_can_I_do.3F'>moral</a> rights;
                            
</li>
<li>
                                Rights other persons may have either in the work itself or in how the work is used, such as <a href='http://wiki.creativecommons.org/Frequently_Asked_Questions#When_are_publicity_rights_relevant.3F'>publicity</a> or privacy rights.
                            
</li>
</ul>
                    
</li>
<li>For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to this web page.
</li>
</ul><p>
            
</p>
<a name="notation-and-conventions"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.2"></a><h3>2.&nbsp;
Notation and Conventions</h3>

<p>
                The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
                "OPTIONAL" in this document are to be interpreted as described in <a class='info' href='#RFC2119'>[RFC2119]<span> (</span><span class='info'>Bradner, B., &ldquo;Key words for use in RFCs to Indicate Requirement Levels,&rdquo; .</span><span>)</span></a>. Domain name examples use
                <a class='info' href='#RFC2606'>[RFC2606]<span> (</span><span class='info'>Eastlake, D. and A. Panitz, &ldquo;Reserved Top Level DNS Names,&rdquo; .</span><span>)</span></a>.
            
</p>
<a name="xml-related-conventions"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.3"></a><h3>3.&nbsp;
XML-Related Conventions</h3>

<p>
                XML elements defined by this specification MAY have an <tt>xml:base</tt>
                attribute <a class='info' href='#W3C.REC-xmlbase'>[W3C.REC&#8209;xmlbase]<span> (</span><span class='info'>Marsh, J. and R. Tobin, &ldquo;XML Base (Second Edition),&rdquo; January&nbsp;2009.</span><span>)</span></a>. 
                When <tt>xml:base</tt> is used, it serves the function described in Section 5.1.1
                of URI Generic Syntax <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, &ldquo;Uniform Resource Identifier (URI): Generic Syntax,&rdquo; January&nbsp;2005.</span><span>)</span></a> by establishing the base URI (or IRI, Internationalized Resource
                Identifier <a class='info' href='#RFC3987'>[RFC3987]<span> (</span><span class='info'>Duerst, M. and M. Suignard, &ldquo;Internationalized Resource Identifiers (IRIs),&rdquo; January&nbsp;2005.</span><span>)</span></a>) for resolving relative references found within the scope of the
                <tt>xml:base</tt> attribute.
            
</p>
<p>
                This specification uses the namespace prefix <tt>atom:</tt> for the Namespace URI identified
                in Section 1.2 of <a class='info' href='#RFC4287'>[RFC4287]<span> (</span><span class='info'>Nottingham, M., Ed. and R. Sayre, Ed., &ldquo;The Atom Syndication Format,&rdquo; December&nbsp;2005.</span><span>)</span></a> and the namespace prefix <tt>xrest:</tt> for the
                Namespace URI identified in <a class='info' href='#extensions'>Section&nbsp;7<span> (</span><span class='info'>Extensions</span><span>)</span></a>.
            
</p>
<a name="definitions"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.4"></a><h3>4.&nbsp;
Definitions</h3>

<p>For convenience, this protocol can be referred to as "eXtensible REST Services Protocol" or "XREST Protocol".
</p>
<p>The term AtomPub referes to the Atom Publishing Protocol <a class='info' href='#RFC5023'>[RFC5023]<span> (</span><span class='info'>Gregorio, J. and B. de hOra, &ldquo;The Atom Publishing Protocol,&rdquo; October&nbsp;2007.</span><span>)</span></a>.
</p>
<p>The following terminology is used by this specification:
                </p>
<blockquote class="text"><dl>
<dt>Client:</dt>
<dd>An HTTP client <a class='info' href='#RFC2616'>[RFC2616]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, &ldquo;Hypertext Transfer Protocol -- HTTP/1.1,&rdquo; .</span><span>)</span></a>.
</dd>
<dt>Host:</dt>
<dd>An HTTP server <a class='info' href='#RFC2616'>[RFC2616]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, &ldquo;Hypertext Transfer Protocol -- HTTP/1.1,&rdquo; .</span><span>)</span></a>. The host is intended to be extended by plugins.
</dd>
<dt>Extension Point:</dt>
<dd>
                        Description of an HTTP request from the client to the host that MAY be extended by plugins.
                        An extension point is composed of the HTTP method (<a class='info' href='#RFC2616'>[RFC2616]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, &ldquo;Hypertext Transfer Protocol -- HTTP/1.1,&rdquo; .</span><span>)</span></a>)
                        and the MIME type of the request (<a class='info' href='#RFC2046'>[RFC2046]<span> (</span><span class='info'>Freed, N. and N. Borenstein, &ldquo;Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types,&rdquo; November&nbsp;1996.</span><span>)</span></a>).
                    
</dd>
<dt>Extension:</dt>
<dd>
                        XML interface that describe the capabilities that the plug-in is offering to the host.
                    
</dd>
<dt>Extension Registry:</dt>
<dd>
                        AtomPub collection, as defined in <a class='info' href='#RFC5023'>[RFC5023]<span> (</span><span class='info'>Gregorio, J. and B. de hOra, &ldquo;The Atom Publishing Protocol,&rdquo; October&nbsp;2007.</span><span>)</span></a> of extensions.
                    
</dd>
<dt>Plug-in:</dt>
<dd>HTTP server with a specific interface to extend a basic functionality from a host.
</dd>
<dt>Callback:</dt>
<dd>HTTP request that the host makes to a plug-in (see <a class='info' href='#runtime'>Section&nbsp;10<span> (</span><span class='info'>Runtime</span><span>)</span></a>).
</dd>
</dl></blockquote><p>
            
</p>
<a name="model"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5"></a><h3>5.&nbsp;
Protocol Model</h3>

<p></p>
<ul class="text">
<li>A path from the host MAY be associated to an extension registry URI (see <a class='info' href='#discovery'>Section&nbsp;6<span> (</span><span class='info'>Discovery</span><span>)</span></a>).
</li>
<li>
                        Extensions provided by the extension registry are published an updated using the AtomPub
                        <a class='info' href='#RFC5023'>[RFC5023]<span> (</span><span class='info'>Gregorio, J. and B. de hOra, &ldquo;The Atom Publishing Protocol,&rdquo; October&nbsp;2007.</span><span>)</span></a>.
                    
</li>
<li>
                        When a client adds an extension, the targeted plug-in is contacted for acknowledgment
                        (see <a class='info' href='#host-plugin-interactions'>Section&nbsp;9.1<span> (</span><span class='info'>Host/Plug-in interactions</span><span>)</span></a>).
                    
</li>
<li>
                        A client performs a request on the host, the request is matched to extensions
                        from the extension registry (<a class='info' href='#extension-points'>Section&nbsp;8<span> (</span><span class='info'>Extension Points</span><span>)</span></a>).
                        For each of the matched extension, the host is performing a callback to the target plug-in
                        (see <a class='info' href='#runtime'>Section&nbsp;10<span> (</span><span class='info'>Runtime</span><span>)</span></a>).
                    
</li>
<li>
                        According to its extension definition (see <a class='info' href='#extensions'>Section&nbsp;7<span> (</span><span class='info'>Extensions</span><span>)</span></a>), a plug-in MAY
                        decorate the response of the host to a client (see <a class='info' href='#decoration'>Section&nbsp;10.4<span> (</span><span class='info'>Decoration</span><span>)</span></a>).
                    
</li>
<li>This specification prevents failures from plug-ins to cause failures on the host or other contributing plug-ins.
</li>
</ul><p>
            
</p>
<a name="relationships"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.1"></a><h3>5.1.&nbsp;
Relationships between Clients, Hosts and Plug-ins</h3>

<p>The types of relationships that MAY exists between clients, hosts and plug-ins are the following:
                    </p>
<ul class="text">
<li>
                            Multiple extension-points may exist for a single host path (see <a class='info' href='#extension-points'>Section&nbsp;8<span> (</span><span class='info'>Extension Points</span><span>)</span></a>).
                        
</li>
<li>
                            A plug-in MAY be extendable and act as an host itself, exposing extension-points and contributing to hosts URIs.
                        
</li>
<li>Multiple plug-ins MAY plug into a single extension-point.
</li>
<li>A single extension MAY contribute to multiple extension-points
</li>
<li>A plug-in MAY plug into a single extension-point mutiple times.
</li>
<li>
                            An extension registry (see <a class='info' href='#extension-registry'>Section&nbsp;9<span> (</span><span class='info'>Extension Registry</span><span>)</span></a>) associated to a path on the host MAY be located on
                            another domain than the host (see <a class='info' href='#discovery'>Section&nbsp;6<span> (</span><span class='info'>Discovery</span><span>)</span></a>).
                        
</li>
<li>Hosts can contribute extensions to themself, as clients.
</li>
<li>A plug-in MAY receive both synchronous and asynchronous callbacks from the host (see <a class='info' href='#runtime'>Section&nbsp;10<span> (</span><span class='info'>Runtime</span><span>)</span></a>).
</li>
</ul><p>
                
</p>
<a name="discovery"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6"></a><h3>6.&nbsp;
Discovery</h3>

<p>
                A client can discover if a path on the host is extentable with the HEAD HTTP method. XREST defines 4 HTTP headers to specify the
                extension capabilities from the host path: <tt>XREST_Registry</tt>, <tt>XREST_Accept</tt>,
                <tt>XREST_Allow</tt> and <tt>XREST_Synchronous</tt>. The freshness and the validity of these
                headers for the client is defined in section 13 of <a class='info' href='#RFC2616'>[RFC2616]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, &ldquo;Hypertext Transfer Protocol -- HTTP/1.1,&rdquo; .</span><span>)</span></a>.
                <br /><hr class="insert" />
<a name="retriving-extension-registries-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
Client                                           Host
  |                                                |
  |  1.) HEAD to the host path                     |
  |-----------------------------------------------&gt;|
  |                                                |
  |  2.) 200 Ok                                    |
  |      XREST_Registry: /registry/index           |
  |      XREST_Accept: */*                         |
  |      XREST_Allow: GET, POST, PUT, DELETE       |
  |      XREST_Synchronous: true                   |
  |&lt;-----------------------------------------------|
  |                                                |
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;1: Extension Registry Discovery&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

                </p>
<ol class="text">
<li>The client sens a HEAD request to the host.
</li>
<li>
                        The host responds with 4 HTTP headers:
                        
<ul class="text">
<li><tt>XREST_Registry</tt>. This field contains the URI of the extension registry.
</li>
<li>
                                <tt>XREST_Accept</tt>: This field contains a semicolon-separated list of 
                                representation schemes (content-type metainformation values <a class='info' href='#RFC2045'>[RFC2045]<span> (</span><span class='info'>Freed, N. and N. Borenstein, &ldquo;Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,&rdquo; November&nbsp;1996.</span><span>)</span></a>) 
                                that extensions MAY plug into (see <a class='info' href='#extension-points'>Section&nbsp;8<span> (</span><span class='info'>Extension Points</span><span>)</span></a>).
                            
</li>
<li>
                                <tt>XREST_Allow</tt>: This field lists the set of methods for 
                                which extensions MAY plug into (see <a class='info' href='#extension-points'>Section&nbsp;8<span> (</span><span class='info'>Extension Points</span><span>)</span></a>).
                            
</li>
<li>
                                <tt>XREST_Synchronous</tt>: Boolean value. Indicates if the plug-in callback is
                                synchronous or asynchronous (see <a class='info' href='#runtime'>Section&nbsp;10<span> (</span><span class='info'>Runtime</span><span>)</span></a>).
                            
</li>
</ul>
                    
</li>
</ol><p>
            
</p>
<a name="extensions"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.7"></a><h3>7.&nbsp;
Extensions</h3>

<p>
                Extensions are defined by plug-ins and are submitted by clients to the host
                (see <a class='info' href='#extension-registry'>Section&nbsp;9<span> (</span><span class='info'>Extension Registry</span><span>)</span></a>).
            
</p>
<p>
                The namespace name <a class='info' href='#W3C.PR-xml-names11'>[W3C.PR&#8209;xml&#8209;names11]<span> (</span><span class='info'>Bray, T., Hollander, D., Layman, A., and R. Tobin, &ldquo;Namespaces in XML 1.1,&rdquo; November&nbsp;2003.</span><span>)</span></a> of an extension is: 
                <tt>http://xrest.googlecode.com/schemas/xrest</tt>.
            
</p>
<p>
                This specification defines a base XML Schema <a class='info' href='#W3C.CR-xmlschema11-2'>[W3C.CR&#8209;xmlschema11&#8209;2]<span> (</span><span class='info'>Thompson, H., Gao, S., Malhotra, A., Peterson, D., and C. Sperberg-McQueen, &ldquo;W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes,&rdquo; April&nbsp;2009.</span><span>)</span></a>
                for extensions (see <a class='info' href='#extension-schema'>Appendix&nbsp;A<span> (</span><span class='info'>Extension XML Schema</span><span>)</span></a>) and require them to be "valid" 
                in the sense used by <a class='info' href='#W3C.REC-xmlbase'>[W3C.REC&#8209;xmlbase]<span> (</span><span class='info'>Marsh, J. and R. Tobin, &ldquo;XML Base (Second Edition),&rdquo; January&nbsp;2009.</span><span>)</span></a>.
            
</p>
<p>
                <br /><hr class="insert" />
<a name="extension-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
&lt;extension xmlns="http://xrest.googlecode.com/schemas/xrest"
           uri="http://plugin.org/index"
           synchronous="false"&gt;
    &lt;hook method="POST" type="application/atom+xml" /&gt;
    &lt;hook method="PUT" type="application/atom+xml" /&gt;
    &lt;header name="oauth_access_token"&gt;82336989-DhVGOaft8D0Qg14QNlEtxFEYKB1FOoNQKCWydZAcg&lt;/header&gt;
    &lt;header name="oauth_access_token_secret"&gt;vdjklxYTgrjuPVsG8lT0B3sFV9ezZSVWmcVBdFF5g&lt;/header&gt;
&lt;/extension&gt;
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;2: Example of a valid XML extension&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

            
</p>
<p>
                </p>
<ul class="text">
<li>
                        The extension above describe an interface with the plug-in located at <tt>http://plugin.org/index</tt>.
                    
</li>
<li>
                        The attribute <tt>synchronous="false"</tt> indicates whether the callback to the plug-in is 
                        synchronous or asynchronous (see <a class='info' href='#runtime'>Section&nbsp;10<span> (</span><span class='info'>Runtime</span><span>)</span></a>).
                    
</li>
<li>
                        The <tt>hook</tt> elements are defining a pattern matching of the HTTP method and content-type
                        from a client request that MUST trigger a request to the plug-in (see <a class='info' href='#extension-points'>Section&nbsp;8<span> (</span><span class='info'>Extension Points</span><span>)</span></a>).
                    
</li>
<li>
                        The <tt>header</tt> elements are defining names and values of HTTP
                        headers that the host MUST send to the plug-in (see <a class='info' href='#callback-parameters'>Section&nbsp;10.3<span> (</span><span class='info'>Callback Parameters</span><span>)</span></a>).
                        In the example above, the extension defines two HTTP headers  <tt>oauth_access_token</tt>
                        and <tt>oauth_access_token_secret</tt>. It is RECOMMENDED that the information contained
                        in this field is nonsensitive (see <a class='info' href='#security-considerations'>Section&nbsp;11<span> (</span><span class='info'>Security Considerations</span><span>)</span></a>).
                    
</li>
</ul><p>
            
</p>
<a name="extension-points"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8"></a><h3>8.&nbsp;
Extension Points</h3>

<p>
                Extension-points are defined with the <tt>XREST_Accept</tt> and
                <tt>XREST_Allow</tt> HTTP headers (see <a class='info' href='#discovery'>Section&nbsp;6<span> (</span><span class='info'>Discovery</span><span>)</span></a>).
                These values are defining the possible values for the hook elements (see <a class='info' href='#extensions'>Section&nbsp;7<span> (</span><span class='info'>Extensions</span><span>)</span></a>)
                for which the plug-in can plug into.
            
</p>
<p>
                An host responding to a discovery request (see <a class='info' href='#discovery'>Section&nbsp;6<span> (</span><span class='info'>Discovery</span><span>)</span></a>) with the following headers:
                <tt>XRest_Allow: POST, PUT</tt> and<tt>XRest_Accept: application/xml</tt>
                MUST accept extensions with the following hook element:
                <br /><hr class="insert" />
<a name="hooks-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
&lt;hook method="POST" type="application/xml" /&gt;
&lt;hook method="POST" type="application/atom+xml" /&gt;
&lt;hook method="POST" type="application/atomsvc+xml" /&gt;
&lt;hook method="PUT" type="application/atom+xml;type=feed" /&gt;
&lt;hook method="PUT" type="application/atom+xml;type=entry" /&gt;
</pre></div><p>

<p style='text-align: center'>The HTTP method MUST be either POST or PUT and the content-type matching application/xml
</p><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;3: Example of accepted hook elements&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

            

<a name="extension-registry"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.9"></a><h3>9.&nbsp;
Extension Registry</h3>

<p>An extension registry is a feed of extension entries.
</p>
<p>
                The term extension entry defines an Atom entry with
                an extension in the <tt>atom:content</tt> element.
                Atom feeds and entries are defined in <a class='info' href='#RFC4287'>[RFC4287]<span> (</span><span class='info'>Nottingham, M., Ed. and R. Sayre, Ed., &ldquo;The Atom Syndication Format,&rdquo; December&nbsp;2005.</span><span>)</span></a>.
                Extensions are defined in <a class='info' href='#extensions'>Section&nbsp;7<span> (</span><span class='info'>Extensions</span><span>)</span></a>.
            
</p>
<p>
                Publishing and editing of extension entries MUST be done in compliance with the
                Atom Publishing Protocol <a class='info' href='#RFC5023'>[RFC5023]<span> (</span><span class='info'>Gregorio, J. and B. de hOra, &ldquo;The Atom Publishing Protocol,&rdquo; October&nbsp;2007.</span><span>)</span></a> .
                Client/host interactions are defined in terms
                of the Atom Publishing Protocol <a class='info' href='#RFC5023'>[RFC5023]<span> (</span><span class='info'>Gregorio, J. and B. de hOra, &ldquo;The Atom Publishing Protocol,&rdquo; October&nbsp;2007.</span><span>)</span></a>.
                Host/plug-in interactions are defined in <a class='info' href='#host-plugin-interactions'>Section&nbsp;9.1<span> (</span><span class='info'>Host/Plug-in interactions</span><span>)</span></a>.
                <br /><hr class="insert" />
<a name="feed-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;feed xmlns="http://www.w3.org/2005/Atom"&gt;
    &lt;title&gt;Extension Registry Example&lt;/title&gt;
    &lt;link rel="self" href="http://example.org/"/&gt;
    &lt;updated&gt;2009-12-13T18:30:02Z&lt;/updated&gt;
    &lt;id&gt;urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6&lt;/id&gt;

    &lt;entry&gt;
        &lt;title&gt;Extension Example&lt;/title&gt;
        &lt;link rel="self" href="http://example.org/2009/12/13/atom03"/&gt;
        &lt;id&gt;urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a&lt;/id&gt;
        &lt;updated&gt;2009-12-13T18:30:02Z&lt;/updated&gt;
        &lt;content type="application/xrest+xml"&gt;
            &lt;extension xmlns="http://xrest.googlecode.com/schemas/xrest"
                       uri="http://plugin.org/index"
                       synchronous="false"&gt;
                &lt;hook method="POST" type="application/atom+xml" /&gt;
                &lt;hook method="PUT" type="application/atom+xml" /&gt;
                &lt;header name="oauth_access_token"&gt;82336989-DhVGOaft8D0Qg14QNlEtxFEYKB1FOoNQKCWydZAcg&lt;/header&gt;
                &lt;header name="oauth_access_token_secret"&gt;vdjklxYTgrjuPVsG8lT0B3sFV9ezZSVWmcVBdFF5g&lt;/header&gt;
            &lt;/extension&gt;
        &lt;/content&gt;
    &lt;/entry&gt;

&lt;/feed&gt;
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;4: Extension Registry Feed Example&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

            
</p>
<a name="host-plugin-interactions"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.9.1"></a><h3>9.1.&nbsp;
Host/Plug-in interactions</h3>

<p>When an extension entry is POSTed to the extension registry, the extension registry MUST get acknowledgement from the targeted plug-in.
                    <br /><hr class="insert" />
<a name="creating-extension-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
Client                               Extension Registry                                Plug-in
  |                                           |                                           |
  |  1.) POST to a extension registry URI     |                                           |
  |      Extension entry                      |                                           |
  |------------------------------------------&gt;|  2.) GET to the plug-in URI               |
  |                                           |  Extension headers                        |
  |                                           |------------------------------------------&gt;|
  |                                           |                                           |
  |                                           |  3.) 200 OK                               |
  |  4.) 201 CREATED                          |&lt;------------------------------------------|
  |      Location: Extension entry URI        |                                           |
  |&lt;------------------------------------------|                                           |
  |                                           |                                           |
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;5: Creating an Extension&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

                    </p>
<ol class="text">
<li>Client POSTs an extension entry to the Extension registry URI.
</li>
<li>Extension registry GETs the plug-in URI with the extension headers.
</li>
<li>If the extension is accepted by the plug-in, it responds with a status code of 200.
</li>
<li>
                            If the extension was created successfully, the extension registry responds with a status code of 201 and a
                            <tt>Location</tt> HTTP header that contains the IRI of the newly created extension entry.
                        
</li>
<li>If the plug-in response is an HTTP error, the extension entry is not aggregated to the feed and the extension
                           registry responds to the client with an HTTP error.
                        
</li>
</ol><p>
                    <br /><hr class="insert" />
<a name="editing-extension-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
Client                               Extension Registry                                Plug-in
  |                                           |                                           |
  |  1.) PUT to a extension extension URI     |                                           |
  |      Atom extension entry                 |                                           |
  |------------------------------------------&gt;|  2.) GET to the plug-in URI               |
  |                                           |  Extension headers                        |
  |                                           |------------------------------------------&gt;|
  |                                           |                                           |
  |                                           |  3.) 200 OK                               |
  |  4.) 200 OK                               |&lt;------------------------------------------|
  |&lt;------------------------------------------|                                           |
  |                                           |                                           |
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;6: Editing an Extension&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

                    </p>
<ol class="text">
<li>Client PUTs an extension entry to the Atom extension entry URI.
</li>
<li>Extension registry GETs the plug-in URI with the extension headers.
</li>
<li>If the extension is accepted by the plug-in, it responds with a status code of 200.
</li>
<li>If the extension was edited successfully, the extension registry responds with a status code of 200 OK.
</li>
<li>
	                       If the plug-in response is an HTTP error, the extension entry is not updated to the feed and the extension
                           registry responds to the client with an HTTP error.
                        
</li>
</ol><p>
                
</p>
<a name="runtime"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.10"></a><h3>10.&nbsp;
Runtime</h3>

<p>When a client makes a request to the host, it MAY trigger callback from the host to a plug-in.
</p>
<p>
                There is two kind of callback: synchronous (<a class='info' href='#asynchronous-callback'>Section&nbsp;10.1<span> (</span><span class='info'>Asynchronous Callback</span><span>)</span></a>)
                and asynchronous (<a class='info' href='#synchronous-callback'>Section&nbsp;10.2<span> (</span><span class='info'>Synchronous Callback</span><span>)</span></a>).
            
</p>
<a name="asynchronous-callback"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.10.1"></a><h3>10.1.&nbsp;
Asynchronous Callback</h3>

<p>Asynchronous callbacks MAY be executed in concurrently.
</p>
<p>An asynchronous callback MUST NOT decorate the host response to the client.
</p>
<p>
                    <br /><hr class="insert" />
<a name="asynchronous-callback-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
Client                             Host                              Plug-in
   |                                  |                                  |
   |     1.) HTTP request             |   2.) POST to the plug-in URI    |
   |&lt;--------------------------------&gt;|       XREST_Method: Method       |
   |                                  |       Host response content      |
   |     3.) HTTP response            |---------------------------------/|
   |&lt;---------------------------------|                                  |
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;7: Asynchronous Callback&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

                    </p>
<ol class="text">
<li>Client performs an HTTP request to the host.
</li>
<li>The request triggers an asynchronous callback to the plug-in.
</li>
<li>The host delivers the HTTP response to the client.
</li>
</ol><p>
                
</p>
<a name="synchronous-callback"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.10.2"></a><h3>10.2.&nbsp;
Synchronous Callback</h3>

<p>
                    <br /><hr class="insert" />
<a name="synchronous-callback-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
Client                               Host                                Plug-in
  |                                    |                                    |
  |  1.) HTTP request                  |                                    |
  |-----------------------------------&gt;|  2.) POST to the plug-in URI       |
  |                                    |      XREST extension headers       |
  |                                    |      Host response content         |
  |                                    |-----------------------------------&gt;|
  |                                    |                                    |
  |                                    |  3.) 200 OK                        |
  |                                    |      Decorated content             |
  | 4.) HTTP Status code               |&lt;-----------------------------------|
  |     Decorated content              |                                    |
  |&lt;-----------------------------------|                                    |
  |                                    |                                    |
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;8: Synchronous Callback&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

                    </p>
<ol class="text">
<li>Client performs an HTTP request to the host.
</li>
<li>The request triggers an synchronous callback to the plug-in.
</li>
<li>The plug-in responds with a decorated content from the callback content (<a class='info' href='#decoration'>Section&nbsp;10.4<span> (</span><span class='info'>Decoration</span><span>)</span></a>).
</li>
<li>The host responds to the client with the decorated content.
</li>
</ol><p>
                
</p>
<a name="callback-parameters"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.10.3"></a><h3>10.3.&nbsp;
Callback Parameters</h3>

<p>A callback to a plug-in MUST be done with the <tt>POST</tt> method.
</p>
<p>Callback parameters are an introspection of the HTTP request the client issued to the host.
</p>
<p>Introspection of the HTTP request issued to the host by the plug-in is limited because of security considerations (see <a class='info' href='#security-considerations'>Section&nbsp;11<span> (</span><span class='info'>Security Considerations</span><span>)</span></a>).
</p>
<p>
                    <br /><hr class="insert" />
<a name="callback-parameters-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
                                                   |
                                                   |
                    Client Request                 |            Host Callback to Plug-in
        |-------------------------------------|    |    |-------------------------------------|
Request | PUT /index http/1.1                 |    |    | POST /index http/1.1                |
        | Host: example.org                   |    |    | Host: plugin.org                    |
        |-------------------------------------|    |    |-------------------------------------|
        | Content-Type: application/json      |    |    | Content-Type: application/json      |
Headers | Content-Length: 163                 |    |    | Content-Lenght: 163                 |
        | Other Headers                       |    |    | XREST_Method: PUT                   |
        |-------------------------------------|    |    | Extension headers                   |
        | {                                   |    |    |-------------------------------------|
        |    "firstName": "John",             |    |    | {                                   |
        |    "lastName": "Smith",             |    |    |    "firstName": "John",             |
        |    "address": {                     |    |    |    "lastName": "Smith",             |
Body    |      "streetAddress": "21 2nd Str", |    |    |    "address": {                     |
        |      "city": "New York",            |    |    |      "streetAddress": "21 2nd Str", |
        |      "state": "NY",                 |    |    |      "city": "New York",            |
        |      "postalCode": 10021            |    |    |      "state": "NY",                 |
        |      }                              |    |    |      "postalCode": 10021            |
        |  }                                  |    |    |      }                              |
        |-------------------------------------|    |    |  }                                  |
                                                   |    |-------------------------------------|
                                                   |
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;9: Callback Parameters&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

                    </p>
<blockquote class="text"><dl>
<dt>Content-Type:</dt>
<dd>Content-Type from the host response to the client.
</dd>
<dt>XREST_Method:</dt>
<dd>HTTP method from the client request.
</dd>
<dt>Content:</dt>
<dd>Content from the host response to the client.
</dd>
<dt>Extension headers:</dt>
<dd>HTTP headers defined in the extension that triggered the callback (see <a class='info' href='#extensions'>Section&nbsp;7<span> (</span><span class='info'>Extensions</span><span>)</span></a>).
</dd>
</dl></blockquote><p>
                
</p>
<a name="decoration"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.10.4"></a><h3>10.4.&nbsp;
Decoration</h3>

<p>When a host executes a synchronous callback, the plug-in response content MUST be delivered by the host to the client.
</p>
<p>The plug-in reponse content-type and the host request content-type MUST be equals
</p>
<p>
                  <br /><hr class="insert" />
<a name="decoration-example"></a>

<p style='text-align: center'>In the following example, the plug-in is decorating the host reponse to the client with geolocalisation information.
</p><div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
                                                   |
                                                   |
              Host Callback to Plug-in             |              Decorated Response
        |-------------------------------------|    |    |-------------------------------------|
Request | PUT /index http/1.1                 |    |    | POST /index http/1.1                |
        | Host: example.org                   |    |    | Host: plugin.org                    |
        |-------------------------------------|    |    |-------------------------------------|
        | Content-Type: application/json      |    |    | Content-Type: application/json      |
Headers | Content-Length: 163                 |    |    | Content-Lenght: 180                 |
        | XREST_Method: PUT                   |    |    |-------------------------------------|
        |-------------------------------------|    |    | {                                   |
        | {                                   |    |    |    "firstName": "John",             |
        |    "firstName": "John",             |    |    |    "lastName": "Smith",             |
        |    "lastName": "Smith",             |    |    |    "address": {                     |
        |    "address": {                     |    |    |      "streetAddress": "21 2nd Str", |
Body    |      "streetAddress": "21 2nd Str", |    |    |      "city": "New York",            |
        |      "city": "New York",            |    |    |      "state": "NY",                 |
        |      "state": "NY",                 |    |    |      "postalCode": 10021,           |
        |      "postalCode": 10021            |    |    |      "lng": 37.441,                 |
        |      }                              |    |    |      "lat": -122.141                |
        |  }                                  |    |    |     }                               |
        |-------------------------------------|    |    |  }                                  |
                                                   |    |-------------------------------------|
                                                   |
</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;10: Example of Plug-in Decoration&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

                

<a name="scheduling"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.10.5"></a><h3>10.5.&nbsp;
Scheduling</h3>

<p>Asynchronous callbacks MAY be executed concurrently.
</p>
<p>Synchronous callback MUST be executed as a pipeline.
</p>
<p>If a callback responds with an HTTP server error, the host MUST ignore it.
	               HTTP server errors are defined in <a class='info' href='#RFC2616'>[RFC2616]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, &ldquo;Hypertext Transfer Protocol -- HTTP/1.1,&rdquo; .</span><span>)</span></a>
</p>
<p>
                    <br /><hr class="insert" />
<a name="synchronous-callbacks-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
Host                              Plug-in A                            Plug-in B
 |                                    |                                    |
 |  1.) Callback to Plug-in A         |                                    |
 |      Content                       |                                    |
 |-----------------------------------&gt;|                                    |
 |  2.) 200 OK                        |                                    |
 |      Decorated content 1           |                                    |
 |&lt;-----------------------------------|                                    |
 |                                    |                                    |
 |  3.) Callback to Plug-in B         |                                    |
 |      Decorated content 1           |                                    |
 |------------------------------------------------------------------------&gt;|
 |  4.) 200 OK                        |                                    |
 |      Decorated content 2           |                                    |
 |&lt;------------------------------------------------------------------------|
 |                                    |                                    |
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;11: Synchronous Callbacks&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

                        </p>
<ol class="text">
<li>Host executes a callback to plug-in A.
</li>
<li>Plug-in A responds with a decorated content.
</li>
<li>Host executes a callback to plug-in B with the decorated content from plug-in A.
</li>
<li>Plug-in B responds with a new decorated content.
</li>
</ol><p>
                    <br /><hr class="insert" />
<a name="synchronous-callbacks-error-example"></a>
</p>
<div style='display: table; width: 0; margin-left: auto; margin-right: auto'><pre>
Host                              Plug-in A                            Plug-in B
 |                                    |                                    |
 |  1.) Callback to Plug-in A         |                                    |
 |      Content                       |                                    |
 |-----------------------------------&gt;|                                    |
 |  2.) 500 ERROR                     |                                    |
 |&lt;-----------------------------------|                                    |
 |                                    |                                    |
 |  3.) Callback to Plug-in B         |                                    |
 |      Content                       |                                    |
 |------------------------------------------------------------------------&gt;|
 |  4.) 200 OK                        |                                    |
 |      Decorated content             |                                    |
 |&lt;------------------------------------------------------------------------|
 |                                    |                                    |
</pre></div><p>
<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b>&nbsp;Figure&nbsp;12: Synchronous Callbacks with Error&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

                    </p>
<ol class="text">
<li>Host executes a callback to plug-in A.
</li>
<li>Plug-in A responds with an HTTP server error.
</li>
<li>Host executes a callback to plug-in B.
</li>
<li>Plug-in B responds with a new decorated content.
</li>
</ol><p>
                 
</p>
<a name="security-considerations"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.11"></a><h3>11.&nbsp;
Security Considerations</h3>

<p>
                The extension registry part of the protocol is based on the Atom Publishing Protocol
                and thus subject to the security considerations found in Section 14 of <a class='info' href='#RFC5023'>[RFC5023]<span> (</span><span class='info'>Gregorio, J. and B. de hOra, &ldquo;The Atom Publishing Protocol,&rdquo; October&nbsp;2007.</span><span>)</span></a>.
            
</p>
<p>HTTP headers that are sent to the host MUST NOT be sent to a plug-in.
</p>
<p>Plug-ins SHOULD prevent a loop of infinite callbacks by avoiding to perform HTTP requests that MAY trigger a callback to the plug-in itself.
</p>
<p>
                The use of an authentication protocol which allows plug-ins to holds some authorization from a third party without requiring either party to disclose its credentials to the other such as OAuth <a class='info' href='#draft-barnes-oauth-model-01'>[draft&#8209;barnes&#8209;oauth&#8209;model&#8209;01]<span> (</span><span class='info'>Hammer-Lahav, E., &ldquo;The OAuth Core 1.0 Protocol,&rdquo; December&nbsp;2009.</span><span>)</span></a>
                is RECOMMENDED.
            
</p>
<a name="rfc.references1"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<h3>12.&nbsp;References</h3>
<table width="99%" border="0">
<tr><td class="author-text" valign="top"><a name="RFC2045">[RFC2045]</a></td>
<td class="author-text"><a href="mailto:ned@innosoft.com">Freed, N.</a> and <a href="mailto:nsb@nsb.fv.com">N. Borenstein</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc2045">Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</a>,&rdquo; RFC&nbsp;2045, November&nbsp;1996 (<a href="ftp://ftp.isi.edu/in-notes/rfc2045.txt">TXT</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC2046">[RFC2046]</a></td>
<td class="author-text"><a href="mailto:ned@innosoft.com">Freed, N.</a> and <a href="mailto:nsb@nsb.fv.com">N. Borenstein</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc2046">Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types</a>,&rdquo; RFC&nbsp;2046, November&nbsp;1996 (<a href="ftp://ftp.isi.edu/in-notes/rfc2046.txt">TXT</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
<td class="author-text">Bradner, B., &ldquo;<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,&rdquo; RFC&nbsp;2119.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC2606">[RFC2606]</a></td>
<td class="author-text">Eastlake, D. and A. Panitz, &ldquo;<a href="http://tools.ietf.org/html/rfc2606">Reserved Top Level DNS Names</a>,&rdquo; RFC&nbsp;2606.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC2616">[RFC2616]</a></td>
<td class="author-text">Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, &ldquo;<a href="http://tools.ietf.org/html/rfc2616">Hypertext Transfer Protocol -- HTTP/1.1</a>,&rdquo; RFC&nbsp;2616.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC3986">[RFC3986]</a></td>
<td class="author-text"><a href="mailto:timbl@w3.org">Berners-Lee, T.</a>, <a href="mailto:fielding@gbiv.com">Fielding, R.</a>, and <a href="mailto:LMM@acm.org">L. Masinter</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc3986">Uniform Resource Identifier (URI): Generic Syntax</a>,&rdquo; STD&nbsp;66, RFC&nbsp;3986, January&nbsp;2005 (<a href="ftp://ftp.isi.edu/in-notes/rfc3986.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc3986.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc3986.xml">XML</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC3987">[RFC3987]</a></td>
<td class="author-text">Duerst, M. and M. Suignard, &ldquo;<a href="http://tools.ietf.org/html/rfc3987">Internationalized Resource Identifiers (IRIs)</a>,&rdquo; RFC&nbsp;3987, January&nbsp;2005 (<a href="ftp://ftp.isi.edu/in-notes/rfc3987.txt">TXT</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC4287">[RFC4287]</a></td>
<td class="author-text"><a href="mailto:mnot@pobox.com">Nottingham, M., Ed.</a> and <a href="mailto:rfsayre@boswijck.com">R. Sayre, Ed.</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc4287">The Atom Syndication Format</a>,&rdquo; RFC&nbsp;4287, December&nbsp;2005 (<a href="ftp://ftp.isi.edu/in-notes/rfc4287.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc4287.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc4287.xml">XML</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC5023">[RFC5023]</a></td>
<td class="author-text">Gregorio, J. and B. de hOra, &ldquo;<a href="http://tools.ietf.org/html/rfc5023">The Atom Publishing Protocol</a>,&rdquo; RFC&nbsp;5023, October&nbsp;2007 (<a href="ftp://ftp.isi.edu/in-notes/rfc5023.txt">TXT</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="W3C.CR-xmlschema11-2">[W3C.CR-xmlschema11-2]</a></td>
<td class="author-text">Thompson, H., Gao, S., Malhotra, A., Peterson, D., and C. Sperberg-McQueen, &ldquo;<a href="http://www.w3.org/TR/2009/CR-xmlschema11-2-20090430">W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes</a>,&rdquo; World Wide Web Consortium CR&nbsp;CR-xmlschema11-2-20090430, April&nbsp;2009 (<a href="http://www.w3.org/TR/2009/CR-xmlschema11-2-20090430">HTML</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="W3C.PR-xml-names11">[W3C.PR-xml-names11]</a></td>
<td class="author-text">Bray, T., Hollander, D., Layman, A., and R. Tobin, &ldquo;<a href="http://www.w3.org/TR/2003/PR-xml-names11-20031105">Namespaces in XML 1.1</a>,&rdquo; W3C PR&nbsp;PR-xml-names11-20031105, November&nbsp;2003.</td></tr>
<tr><td class="author-text" valign="top"><a name="W3C.REC-xmlbase">[W3C.REC-xmlbase]</a></td>
<td class="author-text">Marsh, J. and R. Tobin, &ldquo;<a href="http://www.w3.org/TR/2009/REC-xmlbase-20090128">XML Base (Second Edition)</a>,&rdquo; World Wide Web Consortium Recommendation&nbsp;REC-xmlbase-20090128, January&nbsp;2009 (<a href="http://www.w3.org/TR/2009/REC-xmlbase-20090128">HTML</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="draft-barnes-oauth-model-01">[draft-barnes-oauth-model-01]</a></td>
<td class="author-text">Hammer-Lahav, E., &ldquo;<a href="http://www.ietf.org/internet-drafts/draft-hammer-oauth-08.txt">The OAuth Core 1.0 Protocol</a>,&rdquo; draft-hammer-oauth-08 (work in progress), December&nbsp;2009 (<a href="http://tools.ietf.org/pdf/draft-hammer-oauth-08.txt">PDF</a>, <a href="http://tools.ietf.org/html/draft-hammer-oauth-08.txt">TXT</a>, <a href="http://tools.ietf.org/id/draft-hammer-oauth-08.txt">HTML</a>).</td></tr>
</table>

<a name="extension-schema"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.A"></a><h3>Appendix A.&nbsp;
Extension XML Schema</h3>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
           targetNamespace="http://xrest.googlecode.com/schemas/xrest"
           xmlns:extension="http://xrest.googlecode.com/schemas/xrest"&gt;
      &lt;xs:annotation&gt;
            &lt;xs:documentation&gt;XRest extension schema&lt;/xs:documentation&gt;
      &lt;/xs:annotation&gt;
      &lt;xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/03/xml.xsd" /&gt;
      &lt;xs:element name="extension"&gt;
            &lt;xs:complexType&gt;
                  &lt;xs:sequence&gt;
                        &lt;xs:element maxOccurs="unbounded" ref="extension:hook"/&gt;
                        &lt;xs:element minOccurs="0" maxOccurs="unbounded" ref="extension:header"/&gt;
                  &lt;/xs:sequence&gt;
                  &lt;xs:attribute name="uri" use="required" type="xs:anyURI"/&gt;
                  &lt;xs:attribute name="synchronous" type="xs:boolean"/&gt;
                  &lt;xs:attribute name="priority" type="xs:integer"/&gt;
            &lt;/xs:complexType&gt;
      &lt;/xs:element&gt;
      &lt;xs:element name="hook"&gt;
            &lt;xs:complexType&gt;
                  &lt;xs:attribute name="method" use="required"&gt;
                        &lt;xs:simpleType&gt;
                              &lt;xs:restriction base="xs:token"&gt;
                                    &lt;xs:enumeration value="HEAD"/&gt;
                                    &lt;xs:enumeration value="GET"/&gt;
                                    &lt;xs:enumeration value="POST"/&gt;
                                    &lt;xs:enumeration value="PUT"/&gt;
                                    &lt;xs:enumeration value="DELETE"/&gt;
                              &lt;/xs:restriction&gt;
                        &lt;/xs:simpleType&gt;
                  &lt;/xs:attribute&gt;
                  &lt;xs:attribute name="type" use="required"&gt;
                        &lt;xs:simpleType&gt;
                              &lt;xs:restriction base="xs:string"&gt;
                                    &lt;xs:pattern value=".*/.*"/&gt;
                              &lt;/xs:restriction&gt;
                        &lt;/xs:simpleType&gt;
                        &lt;!-- --&gt;
                        &lt;/xs:attribute&gt;
            &lt;/xs:complexType&gt;
      &lt;/xs:element&gt;
      &lt;xs:element name="header"&gt;
            &lt;xs:complexType mixed="true"&gt;
                  &lt;xs:attribute name="name" use="required" type="xs:string"/&gt;
            &lt;/xs:complexType&gt;
      &lt;/xs:element&gt;
&lt;/xs:schema&gt;
</pre></div>
<a name="specification-feedback"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.B"></a><h3>Appendix B.&nbsp;
Specification Feedback</h3>

<p>
                Feedback on this specification is welcomed via the XREST mailing list, <a href='mailto:xrest@googlegroups.com'>xrest@googlegroups.com</a>. For more information, see <a href='http://groups.google.com/group/xrest'>the XRest group on Google Groups</a>. Also, check out <a href='http://code.google.com/p/xrest/'>other documentation</a>.
            
</p>
<a name="rfc.authors"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<h3>Authors' Addresses</h3>
<table width="99%" border="0" cellpadding="0" cellspacing="0">
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">William Candillon</td></tr>
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">Telecom Lille 1</td></tr>
<tr><td class="author" align="right">Email:&nbsp;</td>
<td class="author-text"><a href="mailto:wcandillon@gmail.com">wcandillon@gmail.com</a></td></tr>
<tr cellpadding="3"><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">Gilles Vanwormhoudt</td></tr>
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">Telecom Lille 1</td></tr>
<tr><td class="author" align="right">Email:&nbsp;</td>
<td class="author-text"><a href="mailto:vanwormhoudt@telecom-lille1.eu">vanwormhoudt@telecom-lille1.eu</a></td></tr>
</table>
</body></html>
